/*
 * Copyright 2012-2021 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.boot.web.servlet.server;

import java.io.File;
import java.nio.charset.Charset;
import java.util.List;
import java.util.Locale;
import java.util.Map;

import javax.servlet.ServletContext;

import org.springframework.boot.web.server.ConfigurableWebServerFactory;
import org.springframework.boot.web.server.Cookie.SameSite;
import org.springframework.boot.web.server.MimeMappings;
import org.springframework.boot.web.server.WebServerFactoryCustomizer;
import org.springframework.boot.web.servlet.ServletContextInitializer;
import org.springframework.boot.web.servlet.WebListenerRegistry;

/**
 * 可配置的 {@link ServletWebServerFactory} 接口。
 *
 * @author Dave Syer
 * @author Andy Wilkinson
 * @author Stephane Nicoll
 * @author Eddú Meléndez
 * @author Brian Clozel
 * @since 2.0.0
 * @see ServletWebServerFactory
 * @see WebServerFactoryCustomizer
 */
public interface ConfigurableServletWebServerFactory
		extends ConfigurableWebServerFactory, ServletWebServerFactory, WebListenerRegistry {

	/**
	 * 设置 Web 服务器的上下文路径。上下文路径应以 "/" 开头，但不能以 "/" 结尾。
	 * 默认上下文路径可以使用空字符串表示。
	 * @param contextPath 要设置的上下文路径
	 */
	void setContextPath(String contextPath);

	/**
	 * 设置部署在 Web 服务器中的应用程序显示名称。
	 * @param displayName 显示名称
	 * @since 1.3.0
	 */
	void setDisplayName(String displayName);

	/**
	 * 设置应用于容器 HTTP 会话支持的配置。
	 * @param session 会话配置
	 */
	void setSession(Session session);

	/**
	 * 设置是否注册 DefaultServlet。从 2.4 版本开始默认值为 {@code false}。
	 * @param registerDefaultServlet 是否注册默认 Servlet
	 */
	void setRegisterDefaultServlet(boolean registerDefaultServlet);

	/**
	 * 设置 MIME 类型映射。
	 * @param mimeMappings MIME 类型映射（默认是 {@link MimeMappings#DEFAULT}）
	 */
	void setMimeMappings(MimeMappings mimeMappings);

	/**
	 * 设置文档根目录，Web 上下文将用来提供静态文件服务。
	 * @param documentRoot 文档根目录，如果不需要则为 {@code null}
	 */
	void setDocumentRoot(File documentRoot);

	/**
	 * 设置除了 {@link ServletWebServerFactory#getWebServer(ServletContextInitializer...)}
	 * 参数外，额外应该应用的 {@link ServletContextInitializer}。此方法会替换之前所有设置或添加的初始化器。
	 * @param initializers 要设置的初始化器列表
	 * @see #addInitializers
	 */
	void setInitializers(List<? extends ServletContextInitializer> initializers);

	/**
	 * 添加 {@link ServletContextInitializer}，这些初始化器除了
	 * {@link ServletWebServerFactory#getWebServer(ServletContextInitializer...)} 参数中的外也会被应用。
	 * @param initializers 要添加的初始化器
	 * @see #setInitializers
	 */
	void addInitializers(ServletContextInitializer... initializers);

	/**
	 * 设置应用于服务器 JSP servlet 的配置。
	 * @param jsp JSP servlet 配置
	 */
	void setJsp(Jsp jsp);

	/**
	 * 设置 Locale 到 Charset 的映射关系。
	 * @param localeCharsetMappings Locale 到 Charset 的映射
	 */
	void setLocaleCharsetMappings(Map<Locale, Charset> localeCharsetMappings);

	/**
	 * 设置应用于容器 {@link ServletContext} 的初始化参数。
	 * @param initParameters 初始化参数
	 */
	void setInitParameters(Map<String, String> initParameters);

	/**
	 * 设置用于获取任意添加的 Cookie 的 {@link SameSite} 属性的
	 * {@link CookieSameSiteSupplier} 列表。此方法会替换之前所有设置或添加的供应者。
	 * @param cookieSameSiteSuppliers 要设置的供应者列表
	 * @see #addCookieSameSiteSuppliers
	 */
	void setCookieSameSiteSuppliers(List<? extends CookieSameSiteSupplier> cookieSameSiteSuppliers);

	/**
	 * 添加 {@link CookieSameSiteSupplier}，用于获取任意添加的 Cookie 的 {@link SameSite} 属性。
	 * @param cookieSameSiteSuppliers 要添加的供应者
	 * @see #setCookieSameSiteSuppliers
	 */
	void addCookieSameSiteSuppliers(CookieSameSiteSupplier... cookieSameSiteSuppliers);

}
